CHANGELOG Wording Inverts Actual Accept Header Ordering

What the bug is and how it manifests

The new CHANGELOG entry (line 10) states: "Custom Accept headers provided via requestInit.headers are now appended to the spec-mandated Accept types instead of being overwritten." In standard English, "X appended to Y" means Y is the base and X is added after — so this sentence implies spec-required types come first, with user custom types added afterward.

However, the actual implementation in streamableHttp.ts does the opposite. The GET SSE path uses: [...(userAccept?.split(',').map(s => s.trim().toLowerCase()) ?? []), 'text/event-stream'] and the POST path uses [...(userAccept?.split(',') ?? []), 'application/json', 'text/event-stream']. User-provided types come first, and spec-required types are appended last.

The specific code path and why it matters

Per RFC 7231, when multiple Accept types share equal q-values, earlier entries carry higher implicit preference. So the actual behavior gives user-provided types higher preference than spec-required types. The CHANGELOG implies the opposite preference ordering. While this ordering may be intentional (user routing hints for proxies need higher preference), the documentation still misrepresents which type comes first.

Addressing the refutation

The refutation argues that user-types-first is intentional for proxy/gateway routing, that CHANGELOG entries are not formal specs, and that this is a version-bump PR. These points are valid context, but they do not resolve the wording inaccuracy. The key claim in the CHANGELOG — that spec-required types are always present — is correct, but the described ordering is backwards. The fix is a one-line wording update, not a code change. Since this CHANGELOG entry appears in this PR's diff, this is the appropriate place to catch it.

Step-by-step proof of the discrepancy

1. User sets requestInit.headers = { Accept: 'application/vnd.proxy-hint' }
2. Code computes types = ['application/vnd.proxy-hint', 'text/event-stream']
3. Final header: Accept: application/vnd.proxy-hint, text/event-stream
4. application/vnd.proxy-hint has higher implicit preference (appears first)
5. CHANGELOG says custom types are "appended to" spec types, which would produce text/event-stream, application/vnd.proxy-hint (spec first, custom second)
6. The actual and described orderings are reversed.

Impact and fix

This is a documentation-only inaccuracy — the functional behavior is correct (spec-required types are always present). The fix is to update the CHANGELOG wording to something like: "spec-mandated Accept types are appended to any custom Accept headers provided via requestInit.headers", which accurately reflects user types appearing first with spec types appended after. The secondary q-value deduplication issue (e.g., text/event-stream; q=0.9 not deduped against text/event-stream) is a pre-existing edge case from PR #1655 and not introduced by this PR.

Analysis

packages/core/package.json currently has zod in two conflicting locations:

1. dependencies (line 51): "zod": "catalog:runtimeShared" — this means zod is a direct dependency that auto-installs for any consumer of core.
2. peerDependencies (line 55): "zod": "catalog:runtimeShared" — combined with peerDependenciesMeta.zod.optional: false (line 62), this signals to package managers that users must install zod themselves as a peer.

These two declarations are semantically contradictory. A direct dependency auto-installs and requires nothing from the consumer; a non-optional peer dependency generates package-manager warnings telling consumers they must install the dependency themselves.

Why existing code does not prevent this

The drop-zod-peer-dep changeset (documented in packages/client/CHANGELOG.md under the 2.0.0-alpha.1 entry) explicitly dropped zod from peerDependencies in @modelcontextprotocol/client and @modelcontextprotocol/server. The changeset file targets those two packages but the same cleanup was not applied to packages/core/package.json. The version bump in this PR touches packages/core/package.json (line 4, version field) but does not address this inconsistency.

Step-by-step proof

1. Open packages/core/package.json.
2. Observe "zod": "catalog:runtimeShared" under dependencies — zod will auto-install in any workspace consuming core.
3. Observe "zod": "catalog:runtimeShared" under peerDependencies — a package manager resolving this package would also emit a peer dependency warning.
4. Observe peerDependenciesMeta.zod.optional: false — this marks the peer as required, not optional, making the warning an error in strict tools.
5. Compare with packages/client/package.json: zod is only in dependencies, no peerDependencies entry — the cleanup was done there.

Impact

Practical impact is minimal: core is "private": true and is never published to npm, so no external consumers will encounter the contradictory peer dependency warning. Within the pnpm workspace the direct dependency satisfies the peer requirement automatically. The issue is purely a documentation/consistency problem.

Fix

Remove the zod entry from peerDependencies and its corresponding peerDependenciesMeta.zod block in packages/core/package.json, matching what was done for the client and server packages in the drop-zod-peer-dep changeset.

@cfworker/json-schema removed from peerDependencies but required at runtime

What the bug is and how it manifests

PR #1843 (commit 7ba58da, merged before this version-bump PR) made two contradictory changes simultaneously: (1) it added new ./validators/cf-worker sub-path exports and workerd condition shims in both @modelcontextprotocol/client and @modelcontextprotocol/server that depend on @cfworker/json-schema, and (2) it removed @cfworker/json-schema from the peerDependencies of both published packages. As a result, any consumer who installs @modelcontextprotocol/server@2.0.0-alpha.3 or @modelcontextprotocol/client@2.0.0-alpha.3 will not have @cfworker/json-schema in their node_modules, and runtime module resolution will fail.

The specific code path that triggers it

The chain is: packages/server/src/shimsWorkerd.ts and packages/client/src/shimsWorkerd.ts export CfWorkerJsonSchemaValidator from '@modelcontextprotocol/core'. packages/core/src/validators/cfWorkerProvider.ts line 11 contains a top-level static import: . The tsdown.config.ts for both client and server uses , which inlines core code directly into the built output bundles. However, @cfworker/json-schema is NOT in noExternal — the config comment explicitly states 'treat all other dependencies as external'. Therefore, the built dist/shimsWorkerd.mjs and dist/validators/cfWorker.mjs both contain a bare external ESM import statement at the top of the file.

Why existing code doesn't prevent it

packages/core/package.json does list @cfworker/json-schema as an optional peerDependency. However, core is and is never published to npm — its peerDependencies declaration is invisible to external consumers. The only package.json files that matter to npm consumers are packages/client/package.json and packages/server/package.json, and in both of those @cfworker/json-schema appears only in devDependencies (not installed for consumers, only for local development).

Impact

There are two affected populations: (1) Any Cloudflare Workers user of either package — the workerd export condition is automatically selected by CF Workers bundlers (Wrangler), so even users who never explicitly import from /validators/cf-worker will get shimsWorkerd.mjs loaded, which immediately fails with a top-level import error. This breaks ALL CF Workers integrations. (2) Users who explicitly import from '@modelcontextprotocol/server/validators/cf-worker' or '@modelcontextprotocol/client/validators/cf-worker' in any environment also get the same failure. No package manager will warn about the missing dependency because there is no peerDependencies declaration in the published packages.

Step-by-step proof

1. Developer runs — installs alpha.3 without @cfworker/json-schema (not in dependencies or peerDependencies).
2. Developer deploys to Cloudflare Workers; Wrangler bundles the app and resolves the ./_shims export with the workerd condition → selects dist/shimsWorkerd.mjs.
3. dist/shimsWorkerd.mjs contains: as a bare ESM import.
4. Module resolution fails: .
5. Deployment fails or the worker crashes on startup with a module-not-found error.

How to fix

Re-add @cfworker/json-schema as an optional peerDependency in both packages/client/package.json and packages/server/package.json, matching the pattern used before PR #1843:

This ensures package managers warn CF Workers users to install the dependency and makes the runtime requirement explicit in the published package metadata.

What the bug is

The new CHANGELOG entry in packages/server/CHANGELOG.md (lines 7–8) reads:

Prevent stack overflow in StreamableHTTPServerTransport.close() with re-entrant guard

No class named StreamableHTTPServerTransport exists anywhere in the codebase. The abbreviated name was informally used in the changeset file (fix-streamable-close-reentrant.md) and propagated into the CHANGELOG by the Changesets tooling.

The specific code that was changed

The re-entrancy fix (a _closed flag check) was applied to WebStandardStreamableHTTPServerTransport.close() in packages/server/src/server/streamableHttp.ts around line 224. A separate NodeStreamableHTTPServerTransport exists in packages/middleware/node. The abbreviated name is ambiguous between both implementations.

Why existing validation doesn't catch it

Changesets generates CHANGELOG prose from the markdown body of changeset files. The changeset author used the shorthand StreamableHTTPServerTransport, and no lint rule or automated check validates class name accuracy inside CHANGELOG prose. The error therefore passed through undetected.

Impact

Developers searching the CHANGELOG or codebase for StreamableHTTPServerTransport will find zero results and may conclude the entry refers to a different or removed class. The ambiguity between WebStandardStreamableHTTPServerTransport and NodeStreamableHTTPServerTransport could also cause confusion about which implementation received the fix. The other 2.0.0-alpha.2 entry in the same file (fix-onerror-callbacks) correctly names WebStandardStreamableHTTPServerTransport, making the inconsistency more jarring.

Step-by-step proof

1. Open packages/server/CHANGELOG.md, lines 7–8: entry says StreamableHTTPServerTransport.close().
2. Search the codebase for class StreamableHTTPServerTransport — zero matches.
3. Search for class WebStandardStreamableHTTPServerTransport — found in packages/server/src/server/streamableHttp.ts:224.
4. Search for class NodeStreamableHTTPServerTransport — found in packages/middleware/node.
5. The same CHANGELOG file, line 99 (alpha.2 entry), correctly uses the full name WebStandardStreamableHTTPServerTransport.

How to fix

Change the CHANGELOG entry to: "Prevent stack overflow in WebStandardStreamableHTTPServerTransport.close() with re-entrant guard".

What the bug is: isCallToolResult in packages/core/src/types/guards.ts contains an early-exit check !("content" in value) that short-circuits for any object without a content own-property, even if that object would parse successfully via the schema. Meanwhile, CallToolResultSchema defines content: z.array(ContentBlockSchema).default([]), so CallToolResultSchema.safeParse({}).success === true. The two are not equivalent.

The migration guide makes an explicit, incorrect equivalence claim: docs/migration.md:450-454 presents isCallToolResult(value) as a direct drop-in replacement for CallToolResultSchema.safeParse(value).success. Any user migrating by substituting isCallToolResult will silently get false for a valid CallToolResult whose content field was omitted in the raw object — e.g. a tool response carrying only structuredContent before going through Zod parsing.

Addressing the refutations: The refutations correctly observe that (a) the TypeScript output type for CallToolResult has content as a required field (Zod's .default([]) makes it required in the output, optional only in input), (b) the MCP spec says content is "always present" for backwards compatibility, and (c) values returned by client.callTool() have already been Zod-parsed so content will be present. These are valid, and they explain why real-world breakage is narrow in normal SDK usage.

However, the refutations do not resolve the issue: the migration guide's equivalence claim is stated unconditionally, without the caveat that it only holds for already-parsed values. A developer writing a custom validator, testing raw server responses, or constructing a CallToolResult-shaped object manually before parsing will encounter a false negative. The guard is intentionally stricter than safeParse, but the migration guide does not communicate this distinction.

Concrete proof: (1) Raw object: { isError: false } — no content key, but valid per schema since content defaults to []. (2) CallToolResultSchema.safeParse({ isError: false }).success returns true. (3) isCallToolResult({ isError: false }) returns false due to the !("content" in value) early exit. (4) A user following the migration guide who swaps step 2 for step 3 silently rejects a valid value.

Impact and fix: The bug's practical blast radius is limited to objects that have not been Zod-parsed yet; in the normal SDK flow those are rare. But this is a published migration guide making a false API contract claim. The fix is either to remove the !("content" in value) early-exit in guards.ts (making the guard consistent with safeParse semantics), or to update the migration guide to clearly document that isCallToolResult is stricter and requires content to be explicitly present in the raw object.

CF Workers validator feature silently absent from alpha.3 CHANGELOG

What the bug is and how it manifests

PR #1843 (commit 7ba58da) landed two concrete, user-visible additions to both @modelcontextprotocol/client and @modelcontextprotocol/server: a new ./validators/cf-worker sub-path export (visible in both packages/client/package.json and packages/server/package.json under exports) and a CfWorkerJsonSchemaValidator class exposed through it. However, the PR author did not create a changeset file for these changes. Because Changesets generates CHANGELOG entries exclusively from changeset files, the alpha.3 CHANGELOG for both packages says nothing about this feature — the client CHANGELOG only mentions the Accept-header fix (PR #1655) and the server CHANGELOG only mentions the stack-overflow fix (PR #1788).

The specific code path

packages/client/package.json (line 28–31) and packages/server/package.json (line 28–31) both contain the "./validators/cf-worker" export entry added by commit 7ba58da. Searching .changeset/ in that commit yields zero results — the three new changeset slugs added in .changeset/pre.json (fix-streamable-close-reentrant, odd-forks-enjoy, zod-json-schema-compat) cover entirely different features. Neither the odd-forks-enjoy slug (which produced the Accept-header entry) nor any other slug mentions CF Workers.

Addressing the refutations

Two verifiers argued this is "not actionable" because the Changesets workflow can only produce entries from changeset files and the version-bump PR cannot retroactively create them. This reasoning is correct about how Changesets generates content automatically, but misses the point: CHANGELOG.md files are plain text and can be edited manually before a PR is merged. Version-bump PRs that accidentally missed changesets are routinely fixed by hand-editing the CHANGELOG before the merge/publish. Since this PR has not yet been merged, the omission is still correctable here. The workflow contract is with the automation, not with the maintainers — maintainers always retain the ability to amend the generated text.

Why existing code does not prevent it

There is no CI check that validates CHANGELOG completeness against the set of merged commits between two version tags. The Changesets action produces whatever its inputs say; it cannot detect omitted changeset files. The alpha pre-release mode does not lower the practical importance of this: the ./validators/cf-worker export is the only documented way to use CF Workers JSON schema validation, and alpha users actively track release notes to find new APIs.

Step-by-step proof

1. Check commit 7ba58da: git show 7ba58da -- .changeset/ returns empty — no changeset file was added.
2. Open packages/client/CHANGELOG.md lines 3–14: only one entry under 2.0.0-alpha.3, referencing PR fix(client): preserve custom Accept headers in StreamableHTTPClientTransport #1655 (Accept headers). No mention of ./validators/cf-worker or CfWorkerJsonSchemaValidator.
3. Open packages/server/CHANGELOG.md lines 3–11: only one entry under 2.0.0-alpha.3, referencing PR fix: prevent stack overflow in transport close with re-entrancy guard #1788 (stack overflow fix). Same omission.
4. Open packages/client/package.json lines 28–31: "./validators/cf-worker" export is present and will ship in alpha.3.
5. A user reading the alpha.3 release notes finds no indication this export exists.

How to fix

Manually add a patch-change entry to both packages/client/CHANGELOG.md and packages/server/CHANGELOG.md under 2.0.0-alpha.3, crediting PR #1843. For example:

- [#1843](https://github.com/modelcontextprotocol/typescript-sdk/pull/1843) Add `./validators/cf-worker` sub-path export and `CfWorkerJsonSchemaValidator` for Cloudflare Workers environments. Import from `@modelcontextprotocol/client/validators/cf-worker` (or `/server/`) to use the workerd-compatible JSON Schema validator.

This is a one-time manual correction; no changeset infrastructure changes are needed.

Guard methods from PR #1842 absent from alpha.3 CHANGELOGs

What the bug is and how it manifests

PR #1842 (commit 1eb80c4, 'v2: add guard methods') added new type guard functions to packages/core/src/types/guards.ts and exported them via packages/core/src/exports/public/index.ts. Because both packages/client/src/index.ts and packages/server/src/index.ts do export * from '@modelcontextprotocol/core/public', these guards became part of the published public API of both @modelcontextprotocol/client@2.0.0-alpha.3 and @modelcontextprotocol/server@2.0.0-alpha.3. However, PR #1842 did not create a changeset file, so the Changesets action generated no CHANGELOG entries for these additions.

The specific code path

The guards flow: packages/core/src/types/guards.ts → re-exported from packages/core/src/exports/public/index.ts (lines 107–115) → consumed via export * from '@modelcontextprotocol/core/public' in both packages/client/src/index.ts and packages/server/src/index.ts. Verifiers confirmed that at minimum isCallToolResult and isJSONRPCResponse are newly introduced in this commit; most other JSONRPC guards in the list may have pre-existed. No .changeset/ file appears in the commit, confirmed by git show 1eb80c4 -- .changeset/ returning empty.

Why existing code does not prevent it

There is no CI check that validates CHANGELOG completeness against the set of merged commits. The Changesets action only generates entries from changeset files it finds; it cannot detect commits that should have had a changeset but did not. This is the same root cause as the CF Workers CHANGELOG omission (PR #1843).

Impact

Users upgrading from alpha.2 to alpha.3 who read the release notes have no way to discover these new type guard exports. Alpha users actively track release notes precisely to find new APIs, so undocumented public additions reduce the practical value of the alpha program. The omission is a documentation gap with no functional impact.

Step-by-step proof

1. git show 1eb80c4 -- .changeset/ returns nothing — PR v2: add guard methods #1842 created no changeset file.
2. Open packages/client/CHANGELOG.md lines 3–14: the only alpha.3 entry is for PR fix(client): preserve custom Accept headers in StreamableHTTPClientTransport #1655 (Accept headers). No mention of any guard function.
3. Open packages/server/CHANGELOG.md lines 3–11: the only alpha.3 entry is for PR fix: prevent stack overflow in transport close with re-entrancy guard #1788 (stack overflow fix). Same omission.
4. Open packages/core/src/exports/public/index.ts lines 107–115: isCallToolResult, isJSONRPCResponse, and related guards are exported.
5. A user reading the alpha.3 release notes finds zero indication that type guards were added to either published package.

How to fix

Manually add a patch-change entry to both packages/client/CHANGELOG.md and packages/server/CHANGELOG.md under 2.0.0-alpha.3, crediting PR #1842. The CHANGELOG files are plain text and can be amended before this PR is merged, as was done for other missed changeset entries.

Server browser export condition routes to CF Workers shim, missing required dependency

What the bug is and how it manifests

packages/server/package.json maps the ./_shims export with the browser condition to dist/shimsWorkerd.d.mts / dist/shimsWorkerd.mjs — the exact same files used for the workerd condition. Standard browser bundlers (Vite, webpack, Rollup, esbuild) automatically select the browser export condition. Any developer bundling @modelcontextprotocol/server for a browser target will silently load shimsWorkerd.mjs, which contains a bare top-level ESM import of @cfworker/json-schema. That package is only listed in devDependencies of the server package — not in dependencies or peerDependencies — so no consumer will have it installed, causing a module-not-found error at build-time or runtime.

The specific code path

shimsWorkerd.ts line 6 re-exports CfWorkerJsonSchemaValidator as DefaultJsonSchemaValidator from @modelcontextprotocol/core. packages/core/src/validators/cfWorkerProvider.ts line 11 contains a static top-level import: import { Validator } from '@cfworker/json-schema'. The tsdown.config.ts for the server sets noExternal: ['@modelcontextprotocol/core'] (inlining core), but @cfworker/json-schema is not in noExternal, so the build leaves a bare external import in the output bundle.

Why existing code doesn't prevent it

The client package (packages/client/package.json) correctly provides a distinct shimsBrowser.mjs for the browser condition. The server has no shimsBrowser.ts at all (only shimsNode.ts and shimsWorkerd.ts). PR #1843 which added CF Workers support created the workerd/browser routing but neglected to either provide a server-specific browser shim or add @cfworker/json-schema to peerDependencies.

Addressing the refutation

One verifier argued that the browser→shimsWorkerd routing is intentional because the server needs CfWorkerJsonSchemaValidator (AJV has Node.js dependencies and cannot run in browsers) and both environments need identical behavior — unlike the client which requires distinct shimsBrowser for CORS_IS_POSSIBLE semantics. This argument about intent is plausible, but it does not resolve the functional bug: regardless of whether the routing is intentional, @cfworker/json-schema is not in dependencies or peerDependencies of the published server package, so no browser bundler user will have it installed. The intent and the implementation are misaligned.

Step-by-step proof

1. Developer runs npm install @modelcontextprotocol/server — @cfworker/json-schema is not installed (only in devDeps, never for consumers).
2. Developer's Vite config targets browser; Vite resolves ./_shims via the browser export condition → gets dist/shimsWorkerd.mjs.
3. dist/shimsWorkerd.mjs contains import { Validator } from '@cfworker/json-schema' as a top-level static import.
4. Vite (or webpack/Rollup/esbuild) cannot resolve @cfworker/json-schema → build error or runtime Module not found crash.
5. This affects all browser-bundled server users, not just CF Workers deployments.

How to fix

Option A (minimal): Add @cfworker/json-schema as an optional peerDependency in packages/server/package.json, matching the pattern in packages/core/package.json. This at minimum warns consumers to install it.

Option B (correct): Create a packages/server/src/shimsBrowser.ts that either provides a pure-browser-compatible JSON schema validator or re-exports from the node shim (process is unavailable in browsers anyway), then point the browser export condition to dist/shimsBrowser.mjs. This matches the client package's architecture and removes the dependency on @cfworker/json-schema for standard browser users entirely.

Option C (simplest safe fix): Remove the browser export condition from ./_shims in packages/server/package.json so browser bundlers fall through to the default (node) shim. If the node shim works in browser contexts for the server use case, this is the least-risk change.

ajv/ajv-formats missing from published runtime dependencies

What the bug is and how it manifests

Both @modelcontextprotocol/server and @modelcontextprotocol/client ship with only zod in their runtime dependencies. However, the built dist/shimsNode.mjs for each package contains top-level bare ESM import statements such as import { Ajv } from "ajv" and import _addFormats from "ajv-formats". Because these modules are not listed in the published package's dependencies, npm/pnpm will never install them for a downstream consumer. The first time any Node.js code path reaches module initialization for shimsNode.mjs, the JavaScript runtime throws ERR_MODULE_NOT_FOUND for ajv.

The specific code path that triggers it

The dependency chain is:

1. packages/server/tsdown.config.ts sets noExternal: ['@modelcontextprotocol/core'], which inlines all of core's TypeScript source directly into the server bundle.
2. packages/core/src/validators/ajvProvider.ts (lines 5–6) has static top-level imports: import { Ajv } from 'ajv' and import _addFormats from 'ajv-formats'. These remain as external references in the inlined bundle because ajv is NOT listed in noExternal.
3. packages/server/src/shimsNode.ts exports AjvJsonSchemaValidator as DefaultJsonSchemaValidator — bundled into dist/shimsNode.mjs.
4. packages/server/src/server/server.ts (line 125) executes this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new DefaultJsonSchemaValidator() for every Server instantiation that omits the option.
5. packages/server/package.json lists only "zod": "catalog:runtimeShared" under dependencies — no ajv or ajv-formats.

The same chain applies identically to @modelcontextprotocol/client and its shimsNode.mjs.

Why existing code doesn't prevent it

packages/core/package.json does list ajv and ajv-formats in its own dependencies. However, core is "private": true and is never published to npm. Its dependency declarations are invisible to external consumers. The only package.json files that matter to npm consumers are the published packages/server/package.json and packages/client/package.json, and both omit ajv entirely. tsdown's platform: 'node' configuration treats all non-noExternal bare module imports as external by design, so the import statements are preserved verbatim in the bundle output.

What the impact would be

This breaks virtually all Node.js consumers of the alpha packages. The DefaultJsonSchemaValidator (i.e., AjvJsonSchemaValidator) is the unconditional default for both Server and Client on Node.js. A user who runs npm install @modelcontextprotocol/server and writes new Server(...) will immediately get ERR_MODULE_NOT_FOUND: Cannot find package 'ajv' — before any MCP logic executes. The only workaround is passing { jsonSchemaValidator: customValidator } on every constructor call, which is undocumented behavior that no alpha user would know to do.

How to fix it

Add ajv and ajv-formats to the runtime dependencies in both packages/server/package.json and packages/client/package.json:

"dependencies": {
    "ajv": "catalog:runtimeShared",
    "ajv-formats": "catalog:runtimeShared",
    "zod": "catalog:runtimeShared"
}

Alternatively, add both to noExternal in each package's tsdown.config.ts to inline them into the bundle, which avoids the peer-install requirement entirely.

Step-by-step proof

1. Install the published package: npm install @modelcontextprotocol/server@2.0.0-alpha.3. Only zod is installed as a transitive dependency; ajv is absent from node_modules.
2. Write: import { Server } from '@modelcontextprotocol/server'; — this resolves dist/index.mjs which imports from ./_shims.
3. ./_shims on Node.js resolves to dist/shimsNode.mjs, which begins with import { Ajv } from "ajv" as its first statement.
4. Node.js attempts to resolve ajv → not found → throws ERR_MODULE_NOT_FOUND immediately at module load time, before any user code executes.
5. new Server(...) is never reached; the entire import fails.

Client shimsBrowser.mjs requires @cfworker/json-schema but it is not in runtime dependencies

What the bug is and how it manifests

packages/client/package.json exports the ./_shims entry with a browser condition that points to dist/shimsBrowser.mjs. This file is built from packages/client/src/shimsBrowser.ts, which exports CfWorkerJsonSchemaValidator as DefaultJsonSchemaValidator from @modelcontextprotocol/core (line 6). packages/core/src/validators/cfWorkerProvider.ts has a static top-level import: import { Validator } from '@cfworker/json-schema' (line 11). The tsdown.config.ts sets noExternal: ['@modelcontextprotocol/core'], so all of core is inlined into the client bundle — but @cfworker/json-schema is NOT in noExternal and therefore remains as a bare external ESM import statement in the emitted dist/shimsBrowser.mjs.

The specific code path that triggers it

Browser bundlers (Vite, webpack, Rollup, esbuild) automatically select the browser export condition when targeting browsers. Any developer building a browser application that imports @modelcontextprotocol/client will have their bundler resolve ./_shims → dist/shimsBrowser.mjs, which immediately encounters import { Validator } from '@cfworker/json-schema' as the first top-level import. Since @cfworker/json-schema is only in devDependencies of packages/client/package.json and not in dependencies or peerDependencies, it is never installed for npm consumers.

Why existing code does not prevent it

packages/core/package.json does list @cfworker/json-schema as an optional peerDependency. However, core is "private": true and never published to npm, so its dependency declarations are invisible to external consumers. The only package.json that matters to browser bundler consumers is packages/client/package.json, and there @cfworker/json-schema appears exclusively in devDependencies. No package manager will warn users to install it, and no bundler will find it in node_modules.

What the impact is

Any developer targeting a browser environment with @modelcontextprotocol/client@2.0.0-alpha.3 will receive a module-not-found error for @cfworker/json-schema at build time (static bundlers like Vite/esbuild) or at runtime. The browser condition is applied automatically — no explicit import of the validator sub-path is needed to trigger this. This bug is distinct from the workerd condition issue (bug_003) and the server browser condition issue (bug_008); the client's shimsBrowser.ts has CORS_IS_POSSIBLE=true semantics distinct from the workerd shim but still uses CfWorkerJsonSchemaValidator, so the same missing dependency applies here.

Step-by-step proof

1. Developer runs npm install @modelcontextprotocol/client@2.0.0-alpha.3 — @cfworker/json-schema is not installed (only in devDependencies, never transitively installed for consumers).
2. Developer's Vite/webpack config targets browser; the bundler resolves ./_shims via the browser export condition → selects dist/shimsBrowser.mjs.
3. dist/shimsBrowser.mjs contains a bare top-level import { Validator } from '@cfworker/json-schema' statement.
4. Bundler cannot resolve @cfworker/json-schema — build fails with module-not-found, or runtime throws ERR_MODULE_NOT_FOUND.
5. new Client() is never reached.

How to fix

Add @cfworker/json-schema as an optional peerDependency in packages/client/package.json. This ensures package managers warn browser-targeting consumers to install @cfworker/json-schema and makes the runtime requirement visible in the published package metadata. Alternatively, add @cfworker/json-schema to noExternal in the client's tsdown.config.ts to bundle it directly.